Creating or Updating Accounts

An account is a unique identifier (UUID) that is used to associate a set of credentials and transactions (i.e. workflow executions) with a customer. Each transaction is associated with one account, and an account can be associated with multiple transactions.

If you are onboarding a new customer, use the POST request to create a new account.
If you are updating an existing account, use the PUT request, with the account ID value as a path parameter.

For the complete API specification see: Account API Reference.

Creating or updating the account is always done through a REST API call, regardless of the integration channel. Account requests are subject to Rate Limits.

Account Request

The request body for either an account creation or account update request is a JSON object.

Required Fields

Field	Type	Max. Length	Notes
customerInternalReference	string	100	Customer internal reference for a request to link it in the customer backend (must not contain any PII). Must not contain any of the following characters: <>"/;`%{}\|
`workflowDefinition` object	string	255	A `key` value is required to specify the workflow for the transaction. Other values may be required, depending on the workflow.

Account Request Body Required Fields Example

{
   "customerInternalReference":"myOrganization",
   "workflowDefinition":{
      "key": 10011
   }
}

Optional Fields

Field	Type	Max. Length	Notes
userReference	string	100	Reference for the end user in the customer backend (must not contain any PII)
reportingCriteria	string	255	Additional information provided by a customer for searching and aggregation purposes
callbackUrl	string	255	Definition of the callback URL for this particular request. Overrides callback URL in the Customer Portal.
tokenLifetime	string	min: 5m, max: 60d, default: 30m	Should be a valid date period unit definition: s - seconds, m - minutes, h - hours d - days. Example: ‘1d’ / ‘30m’ / ‘600s’. Overrides Authorization token lifetime in the Customer Portal.
web	object		Used to override default values that are configured in the Portal. Only relevant for the WEB channel.
userConsent	object		If your integration uses REST APIs for Credential Acquisition you must obtain the end-user's consent to share their personal information with Jumio. See: End-User Consent to Collect Personal Data.
overrideSettings	object		Used to override some tenant settings.

workflowDefinition

A workflowDefinition object is required for all requests, and must include a key value that specifies the workflow for the transaction An executed business process that is associated with an account. The transaction applies credentials for the account to a workflow and contains the decision rendered by the workflow..

Additional objects may be required to configure workflows that use some services An identity verification service provided by Jumio that evaluates a set of credentials and renders a decision. A service is invoked by a workflow. A workflow can invoke a single service or a sequence of services and/or risk signals. or risk signals Risk signals are additional third-party services that can be invoked by a workflow. They are typically used to augment the standard services and provide extra assurance for determining the end user’s fraud risk., including:

credentials object used to specify a particular type of credential to upload for the transaction. For example, the Document Verification service (standalone workflow 10026, or any workflow that uses the Extraction capability to extract data from a Document credential
capabilities object used to specify configuration options for specific capabilities.

credentials

An array of the credentials required for the workflow. A credentials array is required if credentials are going to be uploaded by REST API calls. A credentials array is also used to:

Limit the sets of ID types and countries that are presented to end user during the customer journey. For example, the following limits the end user to choosing either USA or Canada, and either Driving License or ID Card. No other options are presented.
```
"credentials": [
         {
            "category": "ID",
            "country": {
               "predefinedType": "DEFINED",
               "values": ["USA", "CAN"]
            },
            "type": {
               "predefinedType": "DEFINED",
               "values": ["DRIVING_LICENSE", "ID_CARD"]
            }  
         }
      ]
```
Due to a limitation in the Web Client, only the first specified country and type value will be shown to the end user.

Specify a Document credential to use with a Document Verification workflow such as 10026. In this case the type and country must be specified to enable the Extraction capability. For example, the following is required to enable the extraction of expected values from a Bank Statement from the USA:

      "credentials": [
            {
                "category": "DOCUMENT",
                "country": {
                    "predefinedType": "DEFINED",
                    "values": ["USA"]
                },
                "type": {
                    "predefinedType": "DEFINED",
                    "values": ["BS"]
                }  
            }
        ]

Field	Type	Notes
id	string	UUID of the credentials
category	string	Credential category. Possible values: ID DOCUMENT FACEMAP It is not common to specify a FACEMAP. Consult with your account representative for additional information.
country	object	Defined at least one ISO 3166-1 alpha-3 country code for the workflow definition. Possible values: ISO 3166-1 alpha-3 country code
type	object	Defined number of credential type codes. Possible values: ID_CARD DRIVING LICENSE PASSPORT VISA

capabilities

Provide values for capabilities that require additional configuration properties.

Field	Type	Notes
watchlistScreening	object	Override the default search profile.
documentVerification	object	Configure additional capabilities to use with Document Verification.
ekycCheck	object	Used to specify a 1+1 or 2+2 search.
workflowDecision	object	Used to specify a ruleset to use instead of the default ruleset configured for the tenant.
ruleset	object	Override the default ruleset used by the workflow.

watchlistScreening

Used to configure the Watchlist Screening capability by overriding the default searchProfile. Consult your Jumio representative for additional information.

        "capabilities":{
           "watchlistScreening": {
           }
        }

searchProfile is the alphanumeric string that is the identifier for your searchProfile.

documentVerification

Used to disable Extraction in cases where a Document is uploaded to be stored but extracting the data is not required. Consult your Jumio representative for additional information.

        "capabilities": {
            "documentVerification": {
                "enableExtraction": "false"
            }
        }

ekycCheck

Includes a searchType value. Allowed values are:

one if requesting a 1+1 check
two if requesting a 2+x2 check

        "capabilities": {
          "ekycCheck": {
            "searchType": "one"
          }
        }

workflowDecision

Used to specify a ruleset to use instead of the default ruleset configured for the tenant.

        "capabilities": {
          "workflowDecision": {
            "riskScoreRulesetId": "81c616b7-d47e-4cb2-8c4f-17267f2106f3"
          } 
        }

ruleset

Using a workflowDecision objectis preferred to using ruleset for most cases.

Used to specify one or more rulesets to use instead of the default ruleset(s) used by the workflow.

        "capabilities": {
            "ruleset": {
                "ids": ["id1", "id2", "id3"]
            }
        }

The values in the "ids" array are the ruleset IDs of the rulesets you want to use. See also: Working with Rules.

web

These values are only relevant for the WEB channel. They are used to override the default values that are configured in the Portal. See Application Settings

Field	Type	Max. Length	Notes
successUrl	string	1900	URL to which the browser will send the end user at the end of a successful web acquisition user journey. Overrides default success URL.*
errorUrl	string	1900	URL to which the browser will send the end user at the end of a failed web acquisition user journey. Overrides default error URL.*
locale	string	5	Renders content in the specified language. Overrides Default locale.

* Success and error URLs provided through an Account request are less restrictive than the defaults. For example, local domains and schemes for deep linking are supported.

web Object Example

"web":{
    "successUrl":"https://www.yourcompany.com/success",
    "errorUrl":"https://www.yourcompany.com/error",
    "locale":"es"
}

userConsent

See End-User Consent to Collect Personal Data for details.

User Consent JSON

"userConsent": {
    "userIp": "226.80.211.232",
    "userLocation": {
      "country": "USA",
      "state": "IL"
    },
    "consent": {
      "obtained": "yes",
      "obtainedAt": "2022-07-20T17:20:35.000Z"
    }
  }

overrideSettings

You can override some tenant settings for a transaction.

Field	Type	Notes
crossDeviceOnly	boolean	Specifies whether or not the credential acquisition must be done on a mobile device.
crossDeviceOption	string	Specifies how a mobile device can get the connection. Options are: DEFAULT (end user can choose email or QR Code) QR_ONLY (Only the QR Code option will be shown) EMAIL_ONLY (Only the email option will be shown)

overrideSettings Object Example

{
    "customerInternalReference":"myCompany",
    "overrideSettings":{
        "crossDeviceOnly": true,
        "crossDeviceOption":"QR_ONLY"
    },
    "workflowDefinition":{
        ...
    }
}

Account Responses

The response from the API includes the UUID and additional information you will need for the transaction, including:

The account ID and the workflow execution ID for the transaction. These values are used for Viewing or Retrieving Workflow Transactions.
The fully parameterized URL for the Web Client
The authorization token you will need if you are using one of the Mobile SDKs.
Details about the credentials that need to be provided for evaluation by the workflow. This includes data that will be used by the integration channel to upload the credential and associate it with the account.
Workflows that evaluate multiple instances of the same type of credential can provide a "label" value to distinguish between the instances.
The URLs you will use if you are Uploading Credentials using the REST APIs for Credential Acquisition.

Example Account Response

{
    "timestamp": "2022-11-28T23:45:02.536Z",
    "account": {
        "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
    },
    "web": {
        "href": "https://greenunion.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ&locale=en-US"
    },
    "sdk": {
        "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ"
    },
    "workflowExecution": {
        "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
        "credentials": [
            {
                "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            },
            {
                "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            }
        ]
    }
}